ISSUE 🔗

close #132

What is this PR? 🔍

전역 스크롤바 스타일 위에, 필요한 곳에서만 덮어쓸 수 있는 작은 스크롤바 유틸리티 클래스를 추가했습니다.

배경

• 기존 구조: packages/tailwind-config/scrollbar.css에서 * 셀렉터로 전역 스크롤바 두께(8px)를 고정하고 있었습니다.
• 발생 문제: 특정 한두 곳에서만 더 얇은 스크롤바가 필요했지만, 사용 빈도가 낮아 별도 컴포넌트나 variant 체계를 만들 정도는 아니었습니다.
• 해결 방향: class selector가 * selector보다 specificity가 높다는 점을 이용해, opt-in 클래스를 추가해 필요한 요소에만 덮어쓰도록 했습니다.

스크롤바 사이즈 유틸리티

• 변경 요약: .scrollbar-sm 클래스를 추가해 ::-webkit-scrollbar 두께를 4px로 오버라이드할 수 있게 했습니다.
• 이유: 전역 스크롤바(8px)와 별개로 특정 요소에서만 더 얇은 스크롤바가 필요했습니다.
• 구현 방식: .scrollbar-sm::-webkit-scrollbar { width: 4px; height: 4px; }로 선언했습니다. class selector가 기존 *::-webkit-scrollbar selector보다 specificity가 높아 !important 없이 오버라이드됩니다. Firefox의 scrollbar-width는 전역에서 이미 thin(가장 얇은 옵션)으로 설정돼 있어 별도 오버라이드는 필요 없었습니다. 필요한 요소에 className="scrollbar-sm"만 추가하면 적용됩니다.

scrollbar-sm 유틸리티 클래스가 적용되지 않는 문제 해결

문제 상황

scrollbar-sm 클래스로 스크롤바 두께를 4px로 줄이려고 했는데, 기본 스크롤바(8px)와 시각적으로 전혀 구분되지 않는 문제가 있었어요.

css*::-webkit-scrollbar {
  width: 8px;
}

.scrollbar-sm::-webkit-scrollbar {
  width: 4px;
}

CSS 선언 순서도 맞고, DevTools상으로도 .scrollbar-sm::-webkit-scrollbar { width: 4px }가 activated 상태로 잡혔는데도 실제 렌더링에는 전혀 반영되지 않았습니다.

원인 파악

DevTools Computed 탭에서 값을 극단적으로(2px, 20px 등) 바꿔가며 테스트한 결과, ::-webkit-scrollbar 자체가 완전히 무시되고 있다는 것을 확인했습니다.
원인은 같은 요소에 공존하던 표준 스펙 속성이었습니다.

css* {
  scrollbar-width: thin;
  scrollbar-color: var(--color-timo-gray-600) transparent;
}

Chrome 최신 버전은 scrollbar-width/scrollbar-color 같은 표준 스크롤바 속성이 하나라도 지정되어 있으면, 해당 요소를 "표준 스크롤바 렌더링 모드"로 전환하고, 이 모드에서는 ::-webkit-scrollbar/::-webkit-scrollbar-thumb 등 webkit 전용 pseudo-element 커스터마이징을 전부 무시합니다. scrollbar-width만 지웠을 때도 안 됐던 건 scrollbar-color가 여전히 남아있어 계속 표준 모드로 렌더링됐기 때문이었어요.

해결책

두 스펙(webkit 전용 vs 표준)은 같은 요소에서 세밀하게 병행 사용이 불가능하다는 걸 확인했고, 두 가지 옵션을 검토했습니다.

옵션 A: webkit 전용으로 완전 통일 → 두께/색상 모두 세밀 조정 가능, 단 Firefox 미지원
옵션 B: 표준 속성만 사용 → 브라우저 전체 지원, 단 두께는 auto/thin/none 3단계로 제한되어 scrollbar-sm 같은 세밀한 px 조정 불가능

최종 결정

옵션 A를 선택했습니다. scrollbar-width/scrollbar-color를 제거하고 ::-webkit-scrollbar 계열로 통일하여, gray-600 등 디자인 시스템 컬러와 세밀한 두께 조정(scrollbar-sm)을 모두 유지했습니다. 대신 Firefox에서는 스크롤바 커스터마이징이 적용되지 않고 브라우저 기본 스타일로 노출되는데, 이 부분은 디자이너와 협의하여 Firefox 지원 범위에서 제외하기로 합의했습니다.

css* {
  scrollbar-color: var(--color-timo-gray-600) transparent; /* Firefox 폴백용으로 유지 여부 재검토 필요 */
}

*::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}

*::-webkit-scrollbar-track {
  background: transparent;
}

*::-webkit-scrollbar-thumb {
  background-color: var(--color-timo-gray-600);
  border-radius: 9999px;
}

.scrollbar-sm::-webkit-scrollbar {
  width: 4px;
  height: 4px;
}

To Reviewers

단순 CSS 유틸리티 추가이며, 별도 판단이 필요한 구조 선택은 없습니다.

Screenshot 📷

Test Checklist ✔

• pnpm lint 통과
• pnpm check-types 통과
• 로컬 dev 서버에 임시 테스트 페이지를 만들어 scrollbar-sm 적용 시 스크롤바 두께가 얇아지는 것을 확인 (테스트 페이지는 커밋에서 제외하고 삭제)
• pnpm build — 미실행: CI에서 확인 예정